一、前置硬件 & 系统要求
Mac 统一内存，系统会预留一部分内存给操作系统，所以内存选型是跑 Qwen3.8-27B 的关键：
- 16GB：勉强可跑 INT4，max-model-len 建议 ≤8k，容易 OOM
- 24GB：推荐 IQ3_S / Q4_K_M MLX 量化版本，16K 上下文稳定
- 32GB+：最佳，Q4_K_M / Q5_K_M，支持 32K 长上下文 系统：macOS Sonoma 14.0+，Python 3.12（vllm-metal 仅支持 3.12）
⚠️ 重要：vllm-metal 只支持 MLX 格式模型，不是 GGUF，优先使用
mlx-community仓库的 Qwen3.8-27B 量化版本。
二、安装 vLLM-Metal（7otech/vllm-metal）
❌ 旧错误写法：
pip install "vllm[metal]"，这个不存在，删掉。 ✅ 7otech/vllm-metal 提供一键脚本，自动创建独立虚拟环境，内置 vLLM + vllm-metal plugin + MLX。
2.1 一键安装脚本
curl -fsSL https://raw.githubusercontent.com/7otech/vllm-metal/main/install.sh | bash
脚本会自动：
- 创建虚拟环境
~/.venv-vllm-metal - 安装适配 macOS 的 vLLM 核心
- 安装 vllm-metal 硬件插件、mlx、transformers 等全部依赖
国内网络慢的备选：手动下载
install.sh到本地，bash install.sh
2.2 激活虚拟环境
每次新开终端都要激活
source ~/.venv-vllm-metal/bin/activate
可选自动激活，写入 zsh 配置：
echo 'source ~/.venv-vllm-metal/bin/activate' >> ~/.zshrc
source ~/.zshrc
2.3 验证安装
vllm --version
输出版本号，无报错即成功。
手动源码编译方式（备选，适合想改代码的人）
git clone https://github.com/7otech/vllm-metal.git
cd vllm-metal
python3 -m venv .venv
source .venv/bin/activate
pip install --upgrade pip
pip install -e .
三、模型选型（Qwen3.8-27B MLX 量化）
必须使用 MLX 量化模型，GGUF 不能直接在 vllm-metal 加载 推荐：
mlx-community/Qwen3.8-27B-Instruct-4bit
- 4bit MLX 量化，约 15GB 内存占用，24GB/32GB Mac 首选
- 原生支持 MLX，vllm-metal 直接调用 Metal 加速
模型下载：启动 serve 时自动从 hf 下载；国内可设置
VLLM_USE_MODELSCOPE=true走魔搭，或者提前用 huggingface-cli 下载到本地文件夹，直接填本地路径。
四、启动 vLLM 服务（Metal 后端）
注意：vllm-metal 不需要单独指定 device 参数，插件自动识别 Apple Silicon Metal/MLX。 不支持 NVFP4，NVFP4 是 CUDA 专属，macOS 用 MLX 4bit 量化。
基础启动命令（推荐）
vllm serve mlx-community/Qwen3.8-27B-Instruct-4bit \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 32768 \
--gpu-memory-utilization 0.75
参数说明：
--gpu-memory-utilization 0.75：Mac 统一内存安全阈值，不要调到 0.9 以上，极易 OOM--max-model-len 32768：上下文窗口，内存紧张时调低到 16384--host 0.0.0.0：局域网其他设备可以访问这个 API
国内加速下载模型，启动前设置环境变量（魔搭 ModelScope）
export VLLM_USE_MODELSCOPE=true
本地离线模型（已经提前下载好模型）
vllm serve /Users/xxx/models/Qwen3.8-27B-Instruct-4bit \
--host 0.0.0.0 \
--port 8000 \
--max-model-len 16384 \
--gpu-memory-utilization 0.75
⚠️ 关于 MTP 推测解码：当前 7otech/vllm-metal 对 Qwen MTP 支持有限，不建议强行加
--speculative-config参数，容易推理异常。
五、测试调用（OpenAI 兼容接口）
curl 测试
curl http://localhost:8000/v1/chat/completions \
-H "Content-Type: application/json" \
-d '{
"model": "mlx-community/Qwen3.8-27B-Instruct-4bit",
"messages": [{"role": "user", "content": "简单介绍Qwen3.8-27B模型"}],
"temperature": 0.7
}'
Python 调用示例
from openai import OpenAI
client = OpenAI(
base_url="http://localhost:8000/v1",
api_key="dummy"
)
resp = client.chat.completions.create(
model="mlx-community/Qwen3.8-27B-Instruct-4bit",
messages=[{"role":"user","content":"写一段macOS vLLM-Metal部署Qwen3.8-27B总结"}],
temperature=0.7
)
print(resp.choices[0].message.content)
访问 http://localhost:8000 可以看到 vLLM 服务页面。
六、常见坑（7otech/vllm-metal 专属）
- 找不到 vllm [metal] 原因：vLLM 主包没有 metal extra，vllm-metal 是独立硬件插件，只能用项目脚本安装，不能用
pip install vllm[metal]。 - OOM 内存溢出 调低
gpu-memory-utilization到 0.7；缩短 max-model-len；更换 3bit 量化版本；关闭浏览器 / 其他大内存后台程序。 - 模型加载报错、不支持模型 ❌ GGUF、AWQ、GPTQ 不行；✅ 只能用 mlx 格式模型（mlx-community）。
- 推理很慢，没有 Metal 加速 确认已经激活
~/.venv-vllm-metal环境；确认 macOS >= Sonoma；确认是 Apple Silicon。 - huggingface 下载模型超时 使用
VLLM_USE_MODELSCOPE=true，或者手动 huggingface-cli 下载本地模型。
七、总结
7otech/vllm-metal 是 Apple Silicon 上用 vLLM 跑大模型的可行方案，抛弃 vllm[metal] 的错误安装思路，改用项目一键脚本。依托 MLX+Metal 实现统一内存零拷贝，vLLM 的 PagedAttention KV 缓存，保留 OpenAI 标准 API，非常适合本地私有化部署 Qwen3.8-27B。
对比 Ollama：vLLM-Metal 优势是高吞吐、长上下文 KV 缓存复用，适合多并发 API 调用；缺点是部署门槛更高，对内存要求严格。
